Purpose: Order Management System provides two generic web services to post different types of XML messages to Order Management System Cloud Service and to receive response messages. The generic web services enable you to send messages to Order Management System Cloud Service and receive responses without the need of queues. The generic web services allow you to use a single protocol to send messages to Order Management System Cloud Service.
• CWMessageIn web service: The CWMessageIn Web Service works with any of the integration layer processes set up through Working with Integration Layer Processes (IJCT). The target attribute in each inbound message identifies the Order Management System Cloud Service process used to process the message and whether the integration layer job must be started and a queue defined in order for the job to process messages. For example, the CWMessageIn web service can route customer history requests to a process queue set up for the CUST_HIST integration layer process and also route catalog requests to the e-commerce catalog request job. If the target attribute for a customer history request is set to CUSTHISTIN, the CUST_HIST integration layer job can remain inactive and a queue is not required. See CWMessageIn Web Service for more information.
• CWServiceIn web service: The CWServiceIn Web Service does not require an integration layer job to process the message. The type attribute in each inbound message identifies the Order Management System Cloud Service process used to process the message. See CWServiceIn Web Service for more information.
Additional web services: Order Management System Cloud Service also provides the following web services to process specific XML messages:
• CWEmailRequest web service: Used to process an Email Request Message (CWEmailRequest) received from an integrated point-of-sale system.
• CWManifest web service: Used to process a Manifest Pick Request Message (CWManifestPickRequest) and Manifest Ship Request Message (CWManifestShipRequest) received from a PC manifesting station.
• CWOrderIn web service: Used to process an Inbound Order XML Message (CWORDERIN) received from an external system, such as a web storefront.
• CWCustomer web service: Used to process an Inbound Customer Message (CWCustomerIn) received from an external system, such as a point-of-sale system.
• CWReceiptIn web service: Used to process a PO Receipt In XML Message (CWReceiptIn) received from a warehouse management system.
• CWPickIn web service: Used to process a CWPickIn XML Message received from a warehouse management system.
Types of Web Services Available
Order Management System Cloud Service supports the following types of web services:
• SOAP-based web service: In this situation, you use the web service’s .wsdl (Web Services Definition Language) file, which is located on your application server, to control the function of the web service. You send the inbound messages to the URL, or endpoint, specified in this wsdl. The web service routes the messages sent to the endpoint and dispatches them to the correct process queue. If the process generates a response message, the web service routes the response.
If you use a web service’s .wsdl, you need to embed each inbound message in the SOAP (Simple Object Access Protocol) message tags in order for the web service to receive and process it correctly.
• RESTful web service: In this situation, you POST the inbound messages to the web service’s URL, or endpoint, of the RESTful service. The web service routes the messages sent to the endpoint and dispatches them to the correct process queue. If the process generates a response message, the web service routes the response.
If you use a RESTful web service, unless otherwise noted, the individual URLs for the web services use the following format: http://server:port/SerenadeSeam/sxrs/application/service, where server:port identifies the application server where the RESTful service is located and service is the name of the web service to call. For example, to call the CWOrderIn RESTful web service, the URL uses this format: http://server:port/SerenadeSeam/sxrs/application/CWOrderIn
Note: Since SOAP web services will be deprecated in a future release, Oracle recommends that you transition to the use of the RESTful web service.
In this chapter:
- Required Setup for the CWMessageIn Web Service
- Required Setup for the CWServiceIn Web Service
• Generic Web Services: Supported Jobs and Messages
- XML Messages Processed by the CWServiceIn Web Service
- XML Messages Processed By the CWMessageIn Web Service
Overview: The CWMessageIn Web Service works with any of the integration layer processes set up through Working with Integration Layer Processes (IJCT).
The target attribute in each inbound message identifies the Order Management System Cloud Service process used to process the message and whether the integration layer job must be started and a queue defined in order for the job to process messages. For example, the CWMessageIn web service can route customer history requests to a process queue set up for the CUST_HIST integration layer process and also route catalog requests to the e-commerce catalog request job. If the target attribute for a customer history request is set to CUSTHISTIN, the CUST_HIST integration layer job can remain inactive and a queue is not required.
Which messages can you send and receive? See XML Messages Processed By the CWMessageIn Web Service for a list.
Web service authentication? Use the Working with Web Service Authentication (WWSA) menu option to define a valid user for basic web service authentication. If you use Oracle Identity Cloud Service for password authentication, in addition to creating the web service authentication user in Work with Web Service Authentication (WWSA), you must also create a corresponding user profile in Oracle Identity Cloud Service and assign the user to the corresponding web service role defined for the Order Management application.
Do inbound-only messages generate any type of response? The supported messages that are inbound-only generate a simple response of OK. The response is not formatted as an XML message.
Required Setup for the CWMessageIn Web Service
To use the CWMessageIn web service, complete the setup below.
• Setup for the CWMessageIn SOAP-Based Web Service
• Setup for the CWMessageIn RESTful Web Service
• Setup for Integration Layer Jobs
Setup for the CWMessageIn SOAP-Based Web Service
The CWMessageIn web service’s .wsdl (Web Services Definition Language) file, which is located on your application server, controls the function of the CWMessageIn web service. You send the inbound messages to the URL, or endpoint, specified in this wsdl. The CWMessageIn web service routes the messages sent to the endpoint and dispatches them to the correct process queue. If the process generates a response message, the CWMessageIn web service routes the response.
You need to embed each inbound message in the SOAP (Simple Object Access Protocol) message tags in order for the CWMessageIn web service to receive and process it correctly. Also, each inbound message must specify the inbound job name for the integration layer process queue as its target, so the CWMessageIn web service can route the message appropriately.
Determine the endpoint: The endpoint specified in the CWMessageIn.wsdl file is where you need to post messages in order for the CWMessageIn web service to route them. The endpoint is typically set to
http://server:port:8080/CWDirectCPService/services/CWMessageIn, where server:port identifies the application server where the wsdl is located and CWMessageIn is the name of the web service to call.
Note: Since SOAP web services will be deprecated in a future release, Oracle recommends that you transition to the use of the RESTful web service.
Sample Inbound Message in SOAP Envelope
The SOAP-based CWMessageIn web service requires that inbound messages be embedded in SOAP envelope tags. A sample XML message embedded in a SOAP envelope is presented below.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dom="http://dom.w3c.org">
<soapenv:Header/>
<soapenv:Body>
<dom:performAction type="xsd:string"><![CDATA[
<Message source="IDC" target="CUSTHISTIN" type="CWCUSTHISTIN" resp_qmgr="QM_TEST" resp_q="CUSTHISTIN_TEST">
<CustomerHistoryRequest company="6" customer_number="13164" number_of_orders="15" send_detail="N"/>
</Message>]]>
</dom:performAction>
</soapenv:Body>
</soapenv:Envelope>
Setup for the CWMessageIn RESTful Web Service
You POST inbound CWMessageIn messages to the web service’s URL, or endpoint, of the RESTful service. The web service routes the messages sent to the endpoint and dispatches them to the correct process queue. If the process generates a response message, the web service routes the response.
Determine the endpoint: The individual URL for the CWMessageIn RESTful service uses the following format: http://server:port/SerenadeSeam/sxrs/application/CWMessageIn, where server:port identifies the application server where the RESTful service is located and CWMessageIn is the name of the web service to call.
Sample Inbound Message using RESTful Web Service
The CWMessageIn RESTful web service does not require that inbound messages be embedded in SOAP envelope tags. A sample XML message when using a RESTful web service is presented below.
<Message source="IDC" target="CUSTHISTIN" type="CWCUSTHISTIN" resp_qmgr="QM_TEST" resp_q="CUSTHISTIN_TEST">
<CustomerHistoryRequest company="6" customer_number="13164" number_of_orders="15" send_detail="N"/>
</Message>
Setup for Integration Layer Jobs
Set up the integration layer process queues: To set up each integration layer process that will receive messages through the CWMessageIn web service:
1. Create one or more queues for the integration layer process. If the process is inbound-only, it requires only a single queue; otherwise, it requires both an inbound and an outbound queue.
2. Use the Integration Layer Process Queue Screen to create or configure the process queue for the integration layer process, including specifying the inbound and outbound queues.
Determine the target from the process queue: At the Integration Layer Process Queue Screen, determine the Inbound job name for the process queue. The CWMessageIn web service requires that the target specified in the Message element for each inbound message indicate the specific inbound job name used to process the message. See XML Messages Processed By the CWMessageIn Web Service for a table that provides the correct target for each type of message.
Note: If there are multiple process queues for a single integration layer process, each must have a unique Inbound job name. For example, if you receive customer history requests both from the web storefront and from CWStore, you typically set up a separate CUST_HIST process queue for each, using different inbound job names.
Make sure the integration layer processes are running: You need to start most of the related integration layer process(s) in order for them to receive or process messages forwarded by the CWMessageIn web service.
The following integration layer processes can remain inactive and a queue is not required if you enter a specific target in the XML message:
• CUST_HIST process if the target is CUSTHISTIN
• CUSTOMR_IN process if the target is CUSTCRT_IN
• CUST_SRCH process if the target is CWCUSTSRCH
• RETURN_IN process if the target is CWRETURNIN
Overview: The CWServiceIn Web Service does not require an integration layer job to process the message. The type attribute in each inbound message identifies the Order Management System Cloud Service process used to process the message.
Which messages can you send and receive? See XML Messages Processed by the CWServiceIn Web Service for a list.
Web service authentication? Use the Working with Web Service Authentication (WWSA) menu option to define a valid user for basic web service authentication. If you use Oracle Identity Cloud Service for password authentication, in addition to creating the web service authentication user in Work with Web Service Authentication (WWSA), you must also create a corresponding user profile in Oracle Identity Cloud Service and assign the user to the corresponding web service role defined for the Order Management application.
Do inbound-only messages generate any type of response? The supported messages that are inbound-only generate a simple response of OK. The response is not formatted as an XML message. However, the CWProcessIn message, which you can use to start a periodic process, generates a slightly more detailed response.
Required Setup for the CWServiceIn Web Service
To use the CWServiceIn web service, complete the setup below.
• Setup for the CWServiceIn SOAP-Based Web Service
• Setup for the CWServiceIn RESTful Web Service
Setup for the CWServiceIn SOAP-Based Web Service
The CWServiceIn web service’s .wsdl (Web Services Definition Language) file, which is located on your application server, controls the function of the CWServiceIn web service. You send the inbound messages to the URL, or endpoint, specified in this wsdl. The CWServiceIn web service routes the messages sent to the endpoint and dispatches them to the correct Order Management System Cloud Service process. If the Order Management System Cloud Service process generates a response message, the CWServiceIn web service routes the response.
You need to embed each inbound message in the SOAP (Simple Object Access Protocol) message tags in order for the CWServiceIn web service to receive and process it correctly. Also, the type attribute in the inbound message identifies the Order Management System Cloud Service process, so the CWServiceIn web service can route the message appropriately.
To use the CWServiceIn web service, you need to post messages to the endpoint specified in the CWServiceIn.wsdl file in order for the CWServiceIn web service to route them.
Determine the endpoint: The endpoint is typically set to http://server:port/CWDirectCPService/services/CWServiceIn, where server:port identifies the application server where the wsdl is located and CWServiceInis the name of the web service to call.
Note: Since SOAP web services will be deprecated in a future release, Oracle recommends that you transition to the use of the RESTful web service.
Sample Inbound Message in SOAP Envelope
The CWServiceIn web service requires that the inbound messages be embedded in SOAP envelope tags. A sample XML message embedded in a SOAP envelope is presented below.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dom="http://dom.w3c.org">
<soapenv:Header />
<soapenv:Body>
<dom:performAction type="xsd:string">
<![CDATA[
<Message source="External" target="OMS" type="CWORDLNHSTIN" resp_qmgr="" resp_q="">
<Header company_code="7" order_number="3963">
<ShipTos>
<ShipTo ship_to_number="1">
<OrderLineHistorys>
<OrderLineHistory order_detail_seq="1" activity_code="T" quantity="1" contact_date="101112" contact_time="101112" delivery_provider="KB" ext_sys_date="091011" user="SHELDON" ext_ref_nbr="2"/>
</OrderLineHistorys>
</ShipTo>
</ShipTos>
</Header>
</Message>
]]>
</dom:performAction>
</soapenv:Body>
</soapenv:Envelope>
Setup for the CWServiceIn RESTful Web Service
You POST inbound CWServiceIn messages to the web service’s URL, or endpoint, of the RESTful service. The web service routes the messages sent to the endpoint and dispatches them to the correct process queue. If the process generates a response message, the web service routes the response.
Determine the endpoint: Unless otherwise noted, the individual URL for the CWServiceIn RESTful service uses the following format: http://server:port/SerenadeSeam/sxrs/SerenadeREST/CWServiceIn, where server:port identifies the application server where the RESTful service is located and CWServiceIn is the name of the web service to call.
Sample Inbound Message using RESTful Web Service
The CWServiceIn RESTful web service does not require that inbound messages be embedded in SOAP envelope tags. A sample XML message when using a RESTful web service is presented below.
<Message source="External" target="OMS" type="CWORDLNHSTIN" resp_qmgr="" resp_q="">
<Header company_code="7" order_number="3963">
<ShipTos>
<ShipTo ship_to_number="1">
<OrderLineHistorys>
<OrderLineHistory order_detail_seq="1" activity_code="T" quantity="1" contact_date="101112" contact_time="101112" delivery_provider="KB" ext_sys_date="091011" user="SHELDON" ext_ref_nbr="2"/>
</OrderLineHistorys>
</ShipTo>
</ShipTos>
</Header>
</Message>
The CWServiceIn web service requires that the type attribute specified in the Message element identify the Order Management System Cloud Service process used to process the message. See XML Messages Processed by the CWServiceIn Web Service for a table that provides the correct type for each type of message.
Generic Web Services: Supported Jobs and Messages
You can use the generic web services to route any of the inbound messages listed below, and it can then return the outbound messages indicated.
• XML Messages Processed by the CWServiceIn Web Service
• XML Messages Processed By the CWMessageIn Web Service
XML Messages Processed by the CWServiceIn Web Service
Message |
Process |
Type |
Direction |
The type attribute in each inbound message identifies the Order Management System Cloud Service process used to process the message. |
|||
CWOrdLnHstIn |
inbound |
||
Order Transaction History Message (CWOrderTransactionHistory) |
CWOrder TransactionHistory |
inbound |
|
Item Availability Request XML Message (CWItemAvailabilityWeb) |
CWItemAvailabilityWeb |
inbound |
|
Item Availability Response XML Message (CWItemAvailabilityResponseWeb) |
outbound |
||
E-Commerce Availability Web Request XML Message (AvailabilityWebRequest) |
|
AvailabilityWebRequest |
inbound |
E-Commerce Availability Web Response XML Message (AvailabilityWebResponse) |
|
outbound |
|
CWCancel |
inbound |
||
CWCatRequest |
inbound |
||
E-Commerce Catalog Request Response Message (CWCatreqResponse) |
outbound |
||
see Using the CWProcessIn Message to Start a Periodic Process |
CWProcessIn |
inbound |
|
JSON Message Processed by the CWServiceIn Web Service
You can use the CWServiceIn RESTful web service for the Order Broker Product Inventory Availability API to post the Order Broker Product Inventory Availability Request directly to Order Management System Cloud Service and receive the associated response. You POST the Order Broker Product Inventory Availability Request to the web service’s URL, or endpoint, of the RESTful service. The web service routes the messages sent to the endpoint and dispatches them to the Item Availability Update process. When the Item Availability Update process generates an Order Broker Product Inventory Availability Response, the CWServiceIn web service routes the response.
JSON Message |
Process |
Direction |
Item Availability Update |
inbound |
|
outbound |
The individual URL for the CWServiceIn RESTful service used for the Order Broker Product Inventory Availability API uses the following format: http://server/SerenadeSeam/sxrs/Inventory/getAvailable, where server identifies the application server where the RESTful service is located.
For more information: See Order Broker Product Inventory Availability API in the online help for more information.
Troubleshooting the CWServiceIn web service:
If the type specified by an inbound message is not correct, the CWServiceIn web service returns an error such as:
Message>Invalid Target: com.mr.serenade.exception.BOException: MessageInBO.getQueues - Target KB does not match inbound job name</Message>
See the individual messages listed above for more information on message validation.
XML Messages Processed By the CWMessageIn Web Service
Message |
Process(es) |
Direction |
Target |
Integration Layer Processes The following XML messages are processed through the Working with Integration Layer Processes (IJCT) menu option. The target for each inbound message must match the Inbound program name for the integration layer process queue, as specified at the Integration Layer Process Queue Screen. The following integration layer processes can remain inactive and a queue is not required if you enter a specific target in the XML message: • CUST_HIST process if the target is CUSTHISTIN • CUSTOMR_IN process if the target is CUSTCRT_IN or CWCustomerIn • CUST_SRCH process if the target is CWCUSTSRCH • RETURN_IN process if the target is CWRETURNIN |
|||
CUST_SRCH |
inbound |
user-defined; queue not required if target is CWCUSTSRCH |
|
outbound |
|||
Note: Inbound Customer Message (CWCustomerIn)This message typically uses the CWCustomer web service; however, you can use the CWMessageIn web service to route messages for the Generic Customer API if you prefer to use a single endpoint for all messages rather than using the separate endpoint specified in the CWCustomer wsdl file. To use the CWMessageIn web service the type in the message must be CWCustomerIn. For this message, you do not need to set up the CUSTOMR_IN integration layer job. |
CUSTOMR_IN |
inbound |
user-defined; queue not required if type is CWCustomerIn |
outbound |
|||
CUST_HIST |
inbound |
user-defined; queue not required if target is CUSTHISTIN |
|
outbound |
|||
outbound |
|||
inbound |
user-defined |
||
INV_INQURY |
inbound |
user-defined |
|
Inventory Inquiry Response XML Message (CWInventoryInquiryResponse) |
outbound |
||
Inventory Transaction Upload XML Message (inCreateInvXaction) |
INVTRAN_IN |
inbound |
user-defined |
Inbound Order XML Message (CWORDERIN) Note: You can use the CWMessageIn web service to route messages for the Generic Order Interface (Order API) if you prefer to use a single endpoint for all messages rather than using the separate endpoint specified for the CWOrderIn message; however, using the CWMessageIn web service this way requires the same additional setup for the ORDER_IN process as for the other supported integration layer jobs, as described in Required Setup for the CWMessageIn Web Service; you would need to specify inbound and outbound queues and then make sure the ORDER_IN process is active. |
ORDER_IN |
inbound |
user-defined |
Detailed Order XML Response (CWORDEROUT) or |
outbound |
||
RETURN_IN |
inbound |
user-defined; queue not required if target is CWRETURNIN |
|
Note: The returns integration with Oracle Retail Xstore Point-of-Service sends a message with a target of CWRETURNIN, so if you use this integration you need to create a process queue that uses this Inbound job name. |
|||
|
outbound |
||
WORKFLOW |
inbound |
user-defined |
|
Troubleshooting the CWMessageIn web service:
If the target specified by an inbound message is not correct, the generic web service returns an error such as:
Invalid Target
Target OMS does not match inbound job name
